Skip to main content

Universal App

Build cross-platform applications that run seamlessly on Web, iOS, and Android using Catalyst's Universal App architecture.

Overview​

Universal Apps enable you to:

  • Write once, run everywhere (Web, iOS, Android)
  • Access native device capabilities through React hooks
  • Maintain consistent user experience across platforms
  • Leverage platform-specific optimizations

Getting Started​

Core Features​

Architecture​

Universal Apps use a shared codebase with platform-specific adaptations, enabling:

  • Code Reusability: Share business logic across platforms
  • Native Performance: Leverage native capabilities when needed
  • Consistent UX: Maintain design consistency with platform adaptations
  • Developer Productivity: Single codebase, multiple platforms

Frequently Asked Questions (FAQ)​

What is config.json and where should it be located?​

The config.json file is your app's configuration file that tells your development environment how to connect to emulators and set up your development server. It should be placed in your project root directory - the same folder where your package.json file is located.

What is the port number and why do I need to update it?​

The port number (default: 3005) is where your development server runs. Your app connects to this server to get updates and communicate during development. You typically don't need to change it unless:

  • Another application is already using port 3005
  • Your development server is configured to use a different port
  • Your network administrator requires specific ports

Why can't I use spaces in emulator names?​

For Android emulators: Android's command-line tools have issues with spaces in names. Use naming conventions like:

  • ✅ Good: testPhone, myEmulator, pixel7
  • ❌ Avoid: test Phone, my Emulator, pixel 7

For iOS simulators: Spaces are fine in iOS simulator names, so you can use names like iPhone 16 Pro.

How long does the setupEmulator command take?​

First time setup: 2-5 minutes (longer because it sets up ADB connections and validates configurations) Subsequent runs: 30-60 seconds (just starts the emulator)

The command does several things:

  • Validates your SDK setup
  • Checks for running emulators
  • Sets up ADB (Android Debug Bridge) connections
  • Launches the configured emulator

If it seems stuck, wait a few minutes - it's likely downloading or configuring components in the background.

What if my local IP address changes?​

Your local IP address might change when you:

  • Switch between WiFi networks
  • Connect/disconnect from VPN
  • Restart your router

When this happens, you'll need to:

  1. Get your new local IP address (Step 2 in setup)
  2. Update your config.json file with the new IP address
  3. Restart your development server

Common Error Solutions​

  • "Port already in use": Change the port number in your config.json
  • "Emulator not found": Check that your emulator name matches exactly (case-sensitive)
  • "Connection refused": Verify your local IP address is correct and the development server is running
  • "ADB connection issues": Try restarting the emulator or running adb kill-server && adb start-server